Skip to content

docs(0.14): document native asset vault key/value encoding - #371

Merged
BrianSeong99 merged 3 commits into
0xMiden:mainfrom
kutluhaneth46:cursor/docs-v014-asset-encoding-88c1
Oct 12, 2026
Merged

docs(0.14): document native asset vault key/value encoding#371
BrianSeong99 merged 3 commits into
0xMiden:mainfrom
kutluhaneth46:cursor/docs-v014-asset-encoding-88c1

Conversation

@kutluhaneth46

@kutluhaneth46 kutluhaneth46 commented Sep 7, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Fixes Document v0.14 asset encoding in core-concepts/protocol/asset.md #270: documents the v0.14 ASSET_KEY / ASSET_VALUE layout (fungible vs non-fungible, callback flag in faucet_id_suffix) under versioned_docs/version-0.14/reference/protocol/asset.md#encoding.
  • Aligns create_non_fungible_asset Inputs with the fungible helper (enable_callbacks first) in protocol_library.md.
  • Satisfies the existing migration-guide link to #encoding.

Test plan

  • Manual review of the new Encoding section against AssetVaultKey::to_word() on the v0.14.6 tag

BrianSeong99
BrianSeong99 reviewed Sep 8, 2026
View reviewed changes

@BrianSeong99 BrianSeong99 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One correctness issue before approval.

Comment thread versioned_docs/version-0.14/reference/protocol/asset.md Outdated

| Kind | Value word |
| --- | --- |
| Fungible | `[amount, 0, 0, 0]` — `amount ≤ 2⁶³−1` |

@BrianSeong99 BrianSeong99 Sep 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1: The maximum fungible amount in v0.14.6 is 2⁶³−2³¹, not 2⁶³−1. Could we update this row so it matches FungibleAsset::MAX_AMOUNT and FUNGIBLE_ASSET_MAX_AMOUNT?

@kutluhaneth46 kutluhaneth46 Sep 9, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch — updated both places (the vault ASSET_VALUE table row and the earlier fungible-asset prose) to 2⁶³−2³¹, matching FungibleAsset::MAX_AMOUNT / FUNGIBLE_ASSET_MAX_AMOUNT (0x7fffffff80000000).

@kutluhaneth46

kutluhaneth46 commented Sep 9, 2026

Copy link
Copy Markdown
Contributor Author

Addressed @BrianSeong99's P1: fungible max amount is now documented as `2⁶³−2³¹` (not `2⁶³−1`) in both the prose and the `ASSET_VALUE` table, matching `FungibleAsset::MAX_AMOUNT` / `FUNGIBLE_ASSET_MAX_AMOUNT`.

@kutluhaneth46

kutluhaneth46 commented Sep 28, 2026

Copy link
Copy Markdown
Contributor Author

@BrianSeong99 — P1 max-amount fix (2⁶³−2³¹) is in both the prose and the ASSET_VALUE table. Ready for another look / approval when you have a chance.

@kutluhaneth46

kutluhaneth46 commented Oct 1, 2026

Copy link
Copy Markdown
Contributor Author

@BrianSeong99 — gentle bump: P1 max-amount fix is in. Still mergeable/CLEAN if you have a moment for re-review.

@BrianSeong99

BrianSeong99 commented Oct 5, 2026

Copy link
Copy Markdown
Contributor

The maximum-amount correction looks good. Two documentation points still need adjusting before merging:

  1. NFT keys versus tree leaves: NFTs from the same faucet can have distinct asset keys while sharing an SMT leaf. Please avoid implying that each distinct NFT key necessarily maps to a distinct leaf.
  2. Fungible asset merging: Matching faucet IDs alone is insufficient. The callback flags must also match for the assets to share a vault entry and have their amounts merged.

Please also align the older NFT layout/size wording with the updated section so the page is internally consistent.

kutluhaneth46 and others added 3 commits October 5, 2026 16:01
@kutluhaneth46
docs(0.14): document native asset vault key/value encoding
a5d8e00 
Add the ASSET_KEY / ASSET_VALUE layout for fungible and non-fungible
assets, including the callback flag in faucet_id_suffix, and align the
create_non_fungible_asset Inputs row with enable_callbacks.
@kutluhaneth46
docs(0.14): correct fungible MAX_AMOUNT to 2^63-2^31
a68d1e4 
Align the vault encoding table and fungible asset prose with
FungibleAsset::MAX_AMOUNT / FUNGIBLE_ASSET_MAX_AMOUNT (0x7fffffff80000000).
@kutluhaneth46
docs(0.14): clarify NFT leaf sharing and fungible merge rules
699e419 
Address BrianSeong99 review on 0xMiden#371: callback flags gate fungible
merging, NFT vault keys are not 1:1 with SMT leaves, and older
layout/size wording now matches the Encoding section.
@kutluhaneth46

kutluhaneth46 commented Oct 5, 2026

Copy link
Copy Markdown
Contributor Author

Thanks @BrianSeong99 — addressed both points (and aligned the older Type/size wording with the Encoding section):

  1. NFT keys vs leaves: prose + table now say each NFT has a distinct vault key, but distinct keys from the same faucet may still share an SMT leaf (not 1:1).
  2. Fungible merging: faucet id alone is not enough — callback flags must also match for units to share a vault entry and merge amounts (cross-linked to Callbacks).
  3. Consistency: replaced the old “32 bytes / faucet_id as second element” NFT layout wording with the key+value Encoding model.

Ready for another look whenever you have a moment.

@kutluhaneth46
kutluhaneth46 force-pushed the cursor/docs-v014-asset-encoding-88c1 branch from af9c2fe to 699e419 Compare October 5, 2026 16:01
@kutluhaneth46

kutluhaneth46 commented Oct 7, 2026

Copy link
Copy Markdown
Contributor Author

@BrianSeong99 — gentle bump for re-review. The NFT leaf / fungible callback-flag / layout consistency fixes from your Oct 5 notes are on the tip; PR is CLEAN against main. Happy to adjust further if anything still looks off.

@kutluhaneth46

kutluhaneth46 commented Oct 10, 2026

Copy link
Copy Markdown
Contributor Author

@BrianSeong99 — gentle bump for re-review. The NFT leaf / fungible callback-flag / layout consistency fixes from your Oct 5 notes are still on the tip; PR remains CLEAN against main. Happy to adjust further if anything still looks off.

@BrianSeong99
BrianSeong99 merged commit 13f2d4e into 0xMiden:main Oct 12, 2026
@BrianSeong99

BrianSeong99 commented Oct 12, 2026

Copy link
Copy Markdown
Contributor

Thank you for the contribution!

@kutluhaneth46

kutluhaneth46 commented Oct 12, 2026

Copy link
Copy Markdown
Contributor Author

Thanks @BrianSeong99 — appreciate the review and the merge!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@BrianSeong99 BrianSeong99 BrianSeong99 left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Document v0.14 asset encoding in core-concepts/protocol/asset.md

2 participants

@kutluhaneth46 @BrianSeong99